android.ndk.sharedmem source code

1 /*
2  * Copyright (C) 2017 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /**
18  * @addtogroup Memory
19  * @{
20  */
21 
22 /**
23  * @file sharedmem.h
24  * @brief Shared memory buffers that can be shared across process.
25  */
26 
27 module android.ndk.sharedmem;
28 
29 import arsd.jni;
30 import android.ndk;
31 
32 extern (C):
33 nothrow:
34 @nogc:
35 
36 /******************************************************************
37  *
38  * IMPORTANT NOTICE:
39  *
40  *   This file is part of Android's set of stable system headers
41  *   exposed by the Android NDK (Native Development Kit).
42  *
43  *   Third-party source AND binary code relies on the definitions
44  *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
45  *
46  *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
47  *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
48  *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
49  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
50  */
51 
52 /**
53  * Create a shared memory region.
54  *
55  * Create shared memory region and returns an file descriptor.  The resulting file descriptor can be
56  * mmap'ed to process memory space with PROT_READ | PROT_WRITE | PROT_EXEC. Access to shared memory
57  * region can be restricted with {@link ASharedMemory_setProt}.
58  *
59  * Use close() to release the shared memory region.
60  *
61  * Available since API level 26.
62  *
63  * \param name an optional name.
64  * \param size size of the shared memory region
65  * \return file descriptor that denotes the shared memory; error code on failure.
66  */
67 int ASharedMemory_create (const(char)* name, size_t size);
68 
69 /**
70  * Get the size of the shared memory region.
71  *
72  * Available since API level 26.
73  *
74  * \param fd file descriptor of the shared memory region
75  * \return size in bytes; 0 if fd is not a valid shared memory file descriptor.
76  */
77 size_t ASharedMemory_getSize (int fd);
78 
79 /**
80  * Restrict access of shared memory region.
81  *
82  * This function restricts access of a shared memory region. Access can only be removed. The effect
83  * applies globally to all file descriptors in all processes across the system that refer to this
84  * shared memory region. Existing memory mapped regions are not affected.
85  *
86  * It is a common use case to create a shared memory region, map it read/write locally to intialize
87  * content, and then send the shared memory to another process with read only access. Code example
88  * as below (error handling omited).
89  *
90  *
91  *     int fd = ASharedMemory_create("memory", 128);
92  *
93  *     // By default it has PROT_READ | PROT_WRITE | PROT_EXEC.
94  *     size_t memSize = ASharedMemory_getSize(fd);
95  *     char *buffer = (char *) mmap(NULL, memSize, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
96  *
97  *     strcpy(buffer, "This is an example."); // trivially initialize content
98  *
99  *     // limit access to read only
100  *     ASharedMemory_setProt(fd, PROT_READ);
101  *
102  *     // share fd with another process here and the other process can only map with PROT_READ.
103  *
104  * Available since API level 26.
105  *
106  * \param fd   file descriptor of the shared memory region.
107  * \param prot any bitwise-or'ed combination of PROT_READ, PROT_WRITE, PROT_EXEC denoting
108  *             updated access. Note access can only be removed, but not added back.
109  * \return 0 for success, error code on failure.
110  */
111 int ASharedMemory_setProt (int fd, int prot);
112 
113 // __ANDROID_API__ >= 26
114 
115 // ANDROID_SHARED_MEMORY_H
116 
117 /** @} */